Creating and Modifying QT Atom Containers1

QTNewAtomContainer

The QTNewAtomContainer function allows you to create a new atom container.



 
pascal OSErr QTNewAtomContainer (QTAtomContainer *atomData);

atomData: Contains a pointer to an unallocated atom container data structure. On return, this parameter points to an allocated atom container.

DISCUSSION

This function creates a new, empty atom container structure. Once you have created an atom container, you can manipulate it using the atom container functions.

RESULT CODES

`noErr`	0	No error
`paramErr`	-50	Invalid parameter specified
`memFullError`	-108	Not enough memory available

QTInsertChild

The QTInsertChild function creates a new child atom for the specified parent atom.



 
pascal OSErr QTInsertChild (QTAtomContainer container,

                     QTAtom parentAtom,

                     QTAtomType atomType,

                     QTAtomID id,

                     short index,

                     long dataSize,

                     void *data,

                     QTAtom *newAtom);

container: Specifies the atom container that contains the parent atom. The atom container must not be locked.
parentAtom: Specifies the parent atom within the atom container.
atomType: Specifies the type of the new atom to be inserted.
id: Specifies the ID of the new atom to be inserted. This ID must be unique among atoms of the same type for the specified parent. If you set this parameter to 0, this function assigns a unique ID to the atom.
index: Specifies the index of the new atom among atoms with the same parent. To insert the first atom for the specified parent, you should set the index parameter to 1. To insert an atom as the last atom in the child list, you should set the index parameter to 0.
dataSize: Specifies the size of the data for the new atom. If the new atom is to be a parent atom or if you want to add the atom's data later, you should pass 0 for this parameter.
data: Contains a pointer to a buffer containing the data for the new atom. If you set the value of the dataSize parameter to 0, you should pass nil for this parameter.
newAtom: Contains a pointer to data of type QTAtom . On return, this parameter points to the newly created atom. You can pass nil for this parameter if you do not need a reference to the newly created atom.

DISCUSSION

You call this function to create a new child atom. The new child atom has the specified atom type and atom ID, and is inserted into its parent atom's child list at the specified index; any existing atoms at the same index or greater are moved toward the end of the child list. Index values greater than the index of the last atom in the child list plus 1 are invalid.

To create the new atom as a leaf atom that contains data, you should specify the data and its size using the data and dataSize parameters.

RESULT CODES

`noErr`	0	No error
`paramErr`	-50	Invalid parameter specified
`memLockedErr`	-117	Trying to move a locked block
`atomIndexInvalidErr`	-2104	Specified index is out of range
`duplicateAtomTypeAndIDErr`	-2105	An atom with the same type and ID already exists for the specified parent

Memory Manager errors, as documented in Inside Macintosh: Memory .

QTInsertChildren

The QTInsertChildren function inserts a container of atoms as children of the specified parent atom.



 
pascal OSErr QTInsertChildren (QTAtomContainer container,

                     QTAtom parentAtom,

                     QTAtomContainer childrenContainer);

container: Specifies the atom container that contains the parent atom. The atom container must not be locked.
parentAtom: Specifies the parent atom within the atom container.
childrenContainer: Specifies the atom container that contains the child atoms to be inserted.

DISCUSSION

You call this function to insert a container of atoms as children of a parent atom in another atom container. Each child atom is inserted as the last atom of its type and is assigned a corresponding index. The ID of a child atom to be inserted must not duplicate that of an existing child atom of the same type.

RESULT CODES

`noErr`	0	No error
`paramErr`	-50	Invalid parameter specified
`memLockedErr`	-117	Trying to move a locked block
`duplicateAtomTypeAndIDErr`	-2105	An atom with the same type and ID already exists for the specified parent

Memory Manager errors, as documented in Inside Macintosh: Memory .

QTReplaceAtom

The QTReplaceAtom function replaces the contents of an atom and its children with a different atom and its children.



 
pascal OSErr QTReplaceAtom (QTAtomContainer targetContainer,

                     QTAtom targetAtom,

                     QTAtomContainer replacementContainer,

                     QTAtom replacementAtom);

targetContainer: Specifies the atom container that contains the atom to be replaced. The atom container must not be locked.
targetAtom: Specifies the atom to be replaced.
replacementContainer: Specifies the atom container that contains the replacement atom.
replacementAtom: Specifies the replacement atom.

DISCUSSION

The target atom and the replacement atom must be of the same type. The target atom maintains its original atom ID. This function does not modify the replacement container.

RESULT CODES

`noErr`	0	No error
`paramErr`	-50	Invalid parameter specified
`memLockedErr`	-117	Trying to move a locked block
`atomsNotOfSameTypeErr`	-2103	The specified atoms are not of the same type

Memory Manager errors, as documented in Inside Macintosh: Memory .

QTSwapAtoms

The QTSwapAtoms function swaps the contents of two atoms in an atom container.



 
pascal OSErr QTSwapAtoms (QTAtomContainer container,

                     QTAtom atom1,

                     QTAtom atom2);

container: Specifies the atom container for this operation.
atom1: Specifies an atom to be swapped with the atom specified by atom2 .
atom2: Specifies an atom to be swapped with the atom specified by atom1 .

DISCUSSION

You call this function to swap the contents of two atoms in an atom container. After swapping, the ID and index of each atom remains the same. The two atoms specified must be of the same type. Either atom may be a leaf atom or a container atom.

RESULT CODES

`noErr`	0	No error
`paramErr`	-50	Invalid parameter specified
`atomNotOfSameTypeErr`	-2103	The specified atoms are not of the same type

Memory Manager errors, as documented in Inside Macintosh: Memory .

QTSetAtomID

The QTSetAtomID function changes the ID of an atom.



 
pascal OSErr QTSetAtomID (QTAtomContainer container,

                     QTAtom atom,

                     QTAtomID newID);

container: Specifies the atom container for this operation.
atom: Specifies the atom to be modified.
newID: Specifies the new ID for the atom.

DISCUSSION

You cannot change an atom's ID to an ID already assigned to a sibling atom of the same type. Also, you cannot change the ID of the container itself by passing 0 for the atom parameter.

RESULT CODES

`noErr`	0	No error
`duplicateAtomTypeAndIDErr`	-2105	An atom with the same type and ID already exists for the specified parent
`invalidAtomErr`	-2106	Atom specified by container and offset does not exist, container may be invalid

QTSetAtomData

The QTSetAtomData function changes the data of a leaf atom.



 
pascal OSErr QTSetAtomData (QTAtomContainer container,

                     QTAtom atom,

                     long dataSize,

                     void *atomData);

container: Specifies the atom container that contains the atom to be modified.
atom: Specifies the atom to be modified.
dataSize: Specifies the length, in bytes, of the data pointed to by the atomData parameter.
atomData: Contains a pointer to the new data for the atom.

DISCUSSION

You call this function to replace a leaf atom's data with new data. Only leaf atoms contain data; this function returns an error if you pass it to a non-leaf atom.

The atom container specified by the container parameter should not be locked. This function may move memory; if the pointer specified by the atomData parameter is a dereferenced handle, you should lock the handle.

RESULT CODES

`noErr`	0	No error
`paramErr`	-50	Invalid parameter specified
`memLockedErr`	-117	Trying to move a locked block
`notLeafAtomErr`	-2102	Atom specified by container and offset is not a leaf atom

Memory Manager errors, as documented in Inside Macintosh: Memory .

QTCopyAtom

The QTCopyAtom function copies an atom and its children to a new atom container.



 
pascal OSErr QTCopyAtom (QTAtomContainer container,

                     QTAtom atom,

                     QTAtomContainer *targetContainer);

container: Specifies the atom container that contains the atom to be copied.
atom: Specifies the atom to be copied.
targetContainer: Contains a pointer to an uninitialized atom container data structure. On return, this parameter points to an atom container that contains a copy of the atom.

DISCUSSION

To duplicate the entire container specified by the container parameter, you should pass a value of kParentAtomIsContainer for the atom parameter. The caller is responsible for disposing of the new atom container by calling the QTDisposeAtomContainer function.

RESULT CODES

`noErr`	0	No error
`paramErr`	-50	Invalid parameter specified

Memory Manager errors, as documented in Inside Macintosh: Memory .

QTLockContainer

The QTLockContainer function locks an atom container in memory.



 
pascal OSErr QTLockContainer (QTAtomContainer container);

container: Specifies the atom container to be locked.

DISCUSSION

You should call this function to lock an atom container before calling QTGetAtomDataPtr to directly access a leaf atom's data. When you have finished accessing a leaf atom's data, you should call the QTUnlockContainer function.

You may make nested pairs of calls to QTLockContainer and QTUnlockContainer ; you do not need to check the current state of the container first.

RESULT CODES

`noErr`	0	No error
`invalidAtomContainerErr`	-2107	Specified atom container is invalid

QTGetAtomDataPtr

The QTGetAtomDataPtr function retrieves a pointer to the atom data for the specified leaf atom.



 
pascal OSErr QTGetAtomDataPtr (QTAtomContainer container,

                     QTAtom atom,

                     long *dataSize,

                     Ptr *atomData);

container: Specifies the atom container that contains the leaf atom.
atom: Specifies the leaf atom whose data should be retrieved.
dataSize: On return, contains a pointer to the length, in bytes, of the leaf atom's data.
atomData: On return, contains a pointer to the leaf atom's data.

DISCUSSION

You call this function in retrieve a pointer to a leaf atom's data so that you can access the data directly. To ensure that the pointer returned in the atomData parameter will remain valid if memory is moved, you should call QTLockContainer before you call this function. If you call QTLockContainer , you should call QTUnlockContainer when you have finished using the atomData pointer; if you pass a locked atom container to a function that resizes atom containers, the function returns an error.

RESULT CODES

`noErr`	0	No error
`paramErr`	-50	Invalid parameter specified
`notLeafAtomErr`	-2102	Atom specified by container and offset is not a leaf atom

QTUnlockContainer

The QTLockContainer function unlocks an atom container in memory.



 
pascal OSErr QTUnlockContainer (QTAtomContainer container);

container: Specifies the atom container to be unlocked.

DISCUSSION

You should call this function to unlock an atom container when you have finished accessing a leaf atom's data.

You may make nested pairs of calls to QTLockContainer and QTUnlockContainer ; you do not need to check the current state of the container first.

RESULT CODES

`noErr`	0	No error
`invalidAtomContainerErr`	-2107	Specified atom container is invalid

QTRemoveAtom

The QTRemoveAtom function removes an atom and its children from the specified atom container.



 
pascal OSErr QTRemoveAtom (QTAtomContainer container,

                     QTAtom atom);

container: Specifies the atom container for this operation. The atom container must not be locked.
atom: Specifies the atom to be removed from the container.

DISCUSSION

You call this function to remove a particular atom and its children from an atom container. To remove all the atoms in an atom container, you should use the QTRemoveChildren function.

RESULT CODES

`noErr`	0	No error
`paramErr`	-50	Invalid parameter specified
`memLockedErr`	-117	Trying to move a locked block

Memory Manager errors, as documented in Inside Macintosh: Memory .

QTRemoveChildren

The QTRemoveChildren function removes all the children of an atom from the specified atom container.



 
pascal OSErr QTRemoveChildren (QTAtomContainer container,

                     QTAtom atom);

container: Specifies the atom container for this operation. The atom container must not be locked.
atom: Specifies the atom whose children should be removed.

DISCUSSION

To remove all the atoms in the atom container, pass a value of kParentAtomIsContainer for the atom parameter.

RESULT CODES

`noErr`	0	No error
`paramErr`	-50	Invalid parameter specified
`memLockedErr`	-117	Trying to move a locked block

Memory Manager errors, as documented in Inside Macintosh: Memory .

QTDisposeAtomContainer

The QTDisposeAtomContainer function disposes of an atom container.



 
pascal OSErr QTDisposeAtomContainer (QTAtomContainer atomData);

atomData: Specifies the atom container to be disposed of.

DISCUSSION

You can call this function to dispose of an atom container data structure that was created by QTNewAtomContainer or QTCopyAtom .

RESULT CODES

`noErr`	0	No error
`invalidAtomContainerErr`	-2107	Specified atom container is invalid